/*
 *  Copyright 2004 Blandware (http://www.blandware.com)
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package com.blandware.atleap.service.core;

import com.blandware.atleap.common.util.PartialCollection;
import com.blandware.atleap.common.util.QueryInfo;
import com.blandware.atleap.model.core.ContentField;
import com.blandware.atleap.model.core.ContentFieldValue;
import com.blandware.atleap.persistence.exception.DeleteException;
import com.blandware.atleap.service.exception.BeanAlreadyExistsException;
import com.blandware.atleap.service.exception.BeanNotFoundException;

import java.util.List;

/**
 * <p>Business Delegate (Proxy) Interface to handle communication between web and
 * persistence layer.
 * </p>
 * <p><a href="ContentFieldManager.java.html"><i>View Source</i></a>
 * </p>
 *
 * @author Sergey Zubtsovskiy <a href="mailto:sergey.zubtsovskiy@blandware.com">&lt;sergey.zubtsovskiy@blandware.com&gt;</a>
 * @version $Revision: 1.16 $ $Date: 2007/04/03 19:27:21 $
 */
public interface ContentFieldManager extends BaseManager {

	//  F I E L D S

	//~ CRUD Methods ================================================================

	/**
	 * Creates new field
	 *
	 * @param field   ContentField to create
	 * @param ownerId ID of owner localizable to associate field with
	 * @return ID of created field
	 * @throws BeanNotFoundException      if localizable with specified ID couldn't be found
	 * @throws BeanAlreadyExistsException if content field with such identifier already exists on localizable with specified ID
	 */
	public Long createContentField(ContentField field, Long ownerId) throws BeanNotFoundException, BeanAlreadyExistsException;

	/**
	 * Retrieves field with specified ID
	 *
	 * @param fieldId the ID of field to retrieve
	 * @return Content field or null if no field with specified ID exists in database
	 */
	public ContentField retrieveContentField(Long fieldId);

	/**
	 * Updates field
	 *
	 * @param field         ContentField to update
	 * @param localizableId ID of localizable to associate field with
	 * @throws BeanNotFoundException      if localizable with specified ID couldn't be found
	 * @throws BeanAlreadyExistsException if content field with such identifier already exists on localizable with specified ID
	 */
	public void updateContentField(ContentField field, Long localizableId) throws BeanNotFoundException, BeanAlreadyExistsException;


	/**
	 * Removes localizable field
	 *
	 * @param fieldId ID of localizable field to remove
	 * @throws BeanNotFoundException if contentField with specified ID couldn't be found
	 * @throws DeleteException       if content field cannot be deleted (e.g. it has one or more associated values)
	 */
	public void deleteContentField(Long fieldId) throws BeanNotFoundException, DeleteException;

	// ~ Additional methods ================================================================

	/**
	 * Retrieves filtered/sorted collection of localizable fields
	 *
	 * @param queryInfo Object that contains information about how to filter and sort data
	 * @return Collection of content fields
	 */
	public PartialCollection listContentFields(QueryInfo queryInfo);

	// ~ Finders ================================================================

	/**
	 * Finds content field by layout definition and identifier
	 *
	 * @param identifier Identifier of content field to search by
	 * @param definition Struts tile definition on which layout is based
	 * @return Content field or null if nothing was found
	 */
	public ContentField findContentFieldByLayoutDefinition(String identifier, String definition);

	/**
	 * Finds content field by page URI and identifier
	 *
	 * @param identifier Identifier of content field to search by
	 * @param uri        URI of page to which content field belongs
	 * @return Content field or null if nothing was found
	 */
	public ContentField findContentFieldByPageUri(String identifier, String uri);

    /**
     * Finds indexed content fields by identifier prefix and layout definition.
     *
     * @param identifier Identifier prefix of field to search by
     * @param definition Struts tile definition on which localizable is based
     * @return List of content fields or null if nothing was found
     */
    public List findIndexedContentFieldsByLayoutDefinition(String identifier, String definition);

    /**
     * Finds indexed content fields by identifier prefix and layout definition;
     * only fields that have CFVs for specified locale (or default locale) are
     * returned
     *
     * @param identifier Identifier prefix of field to search by
     * @param definition Struts tile definition on which localizable is based
     * @param locale     Content locale for which fields must have values
     * @return List of content fields or null if nothing was found
     */
    public List findIndexedContentFieldsByLayoutDefinitionAndLocale(String identifier, String definition, String locale);

    /**
     * Finds indexed content fields by page URI and identifier prefix.
     *
     * @param identifier Identifier of field to search by
     * @param uri        URI of page to which content fields belong
     * @return List of content fields or null if nothing was found
     */
    public List findIndexedContentFieldsByPageUri(String identifier, String uri);

    /**
     * Finds indexed content fields by page URI and identifier prefix;
     * only fields that have CFVs for specified locale (or default locale) are
     * returned
     *
     * @param identifier Identifier of field to search by
     * @param uri        URI of page to which content fields belong
     * @param locale     Content locale for which fields must have values
     * @return List of content fields or null if nothing was found
     */
    public List findIndexedContentFieldsByPageUriAndLocale(String identifier, String uri, String locale);


    
	//  C O N T E N T    F I E L D    V A L U E

	//~ CRUD Methods ================================================================

	/**
	 * Creates new content field value
	 *
	 * @param contentFieldValue content field value to create
	 * @param fieldId           ID of content field to create value for
     * @param localeIdentifier the identifier of content locale to assosiate this
     * CFV with
	 * @return ID of created content field value
	 * @throws BeanNotFoundException      if content field with specified ID couldn't be found
	 * @throws BeanAlreadyExistsException if content field value already exists for content field with specified identifier and locale
	 */
	public Long createContentFieldValue(ContentFieldValue contentFieldValue, Long fieldId, String localeIdentifier) throws BeanNotFoundException, BeanAlreadyExistsException;

	/**
	 * Retrieves content field value with specified ID
	 *
	 * @param contentFieldValueId the id of CFV to retrieve
	 * @return Content field value or null if no content field value with specified ID exists in database
	 */
	public ContentFieldValue retrieveContentFieldValue(Long contentFieldValueId);

	/**
	 * Updates content field value
	 *
     * @param contentFieldValue the content field value to update
	 * @param fieldId Content field to update value for
     * @param localeIdentifier the identifier of content locale to assosiate this
     * CFV with
	 * @throws BeanNotFoundException      if field value with specified ID couldn't be found
	 * @throws BeanAlreadyExistsException if field content already exists for field with specified identifier and locale
	 */
	public void updateContentFieldValue(ContentFieldValue contentFieldValue, Long fieldId, String localeIdentifier) throws BeanNotFoundException, BeanAlreadyExistsException;


	/**
	 * Removes content field value with specified ID
	 *
	 * @param contentFieldValueId ID of content field value to remove
	 * @throws BeanNotFoundException if content field with specified ID couldn't be found
	 */
	public void deleteContentFieldValue(Long contentFieldValueId) throws BeanNotFoundException;

	// ~ Additional methods ================================================================

	/**
	 * Retrieves filtered/sorted collection of content field values
	 *
	 * @param queryInfo Object that contains information about how to filter and sort data
	 * @return Collection of content field values
	 */
	public PartialCollection listContentFieldValues(QueryInfo queryInfo);

	// ~ Finders ================================================================

	/**
	 * Finds content field value by page URI, field identifier and locale
	 *
	 * @param uri              URI of page that contains field
	 * @param identifier       Identifier of content field
	 * @param localeIdentifier Content locale identifier
	 * @return Content field value or null if nothing was found
	 */
	public ContentFieldValue findContentFieldValueByUriAndIdentifierAndLocale(String uri, String identifier, String localeIdentifier);

	/**
	 * Finds content field value by layout definition, field identifier and locale
	 *
	 * @param definition       Struts tile definition of page that contains field
	 * @param identifier       Identifier of content field
	 * @param localeIdentifier Content locale identifier
	 * @return Content field value or null if nothing was found
	 */
	public ContentFieldValue findContentFieldValueByDefinitionAndIdentifierAndLocale(String definition, String identifier, String localeIdentifier);

    /**
     * Finds content field value by localizable id, field identifier and locale
     *
     * @param localizableId    ID of localizable object
     * @param identifier       Identifier of content field
     * @param localeIdentifier Content locale identifier
     * @return Content field value or null if nothing was found
     */
    public ContentFieldValue findContentFieldValueByLocalizableIdAndIdentifierAndLocale(Long localizableId, String identifier, String localeIdentifier);

	/**
	 * Finds content field value by content field ID and locale
	 *
	 * @param fieldId    ID of content field
	 * @param localeIdentifier Content locale identifier
	 * @return Content field value or null if nothing was found
	 */
	public ContentFieldValue findContentFieldValueByContentFieldIdAndLocale(Long fieldId, String localeIdentifier);

}
